REST Custom Function

/rest/custom_function

https://<username>:<password>@<host>/rest/custom_function

Create or view a list of all custom functions.

POST

Create a custom function.

Request parameters

Field	Required	Type	Description
name	required	string	A unique name per repository that identifies the custom function.
scm_id	required	string	The ID for an existing repository on the system.
description	optional	string	Descriptive text for the custom function. This field displays when selecting custom functions inside the playbook editor.
commit_message	Dependency of a Python field	string	This field is required if the Python field is passed. This message is used for the commit of the changed Python and metadata files to the connected repository.
python	optional	string	Python code that executes for the custom function when it is included in a playbook.

<Returned values>

None.

Fields for both creating and updating a custom function

Field	Required	Type	Default	Description
draft_mode	optional	Boolean	true	A flag to mark a custom function as a draft version. This flag allows you to save invalid Python code while draft_mode is set to true.
python	optional	string	true	Python code that executes for the custom function when it is included in a playbook.
description	optional	string	true	Descriptive text for the custom function. This field displays when selecting custom functions inside the playbook editor.
commit_message	Dependency of a Python field	string	true	This field is required if the Python field is passed. This message is used for the commit of the changed Python and metadata files to the connected repository.
inputs	optional	JSON object	{}	Inputs are used for configuring the custom function in the playbook editor. Example value: [ { "description": "fgh", "contains_type" : ["ip"] , "name": "fgh" } ]
outputs	optional	JSON object	{}	Outputs are used for configuring downstream blocks from the custom function in the playbook editor. Example value: [ { "data_path": "ip", "description": "This is an ip", "contains_type" : ["ip"], } ]

Example request and response
This example JSON request shows creating the draft version of a non-draft custom function, and giving that draft version a different description. This request doesn't disable the current custom function, so it doesn't affect any playbooks using this custom function.

JSON request

curl -k -u admin:changeme https://localhost/rest/custom_function \
-d '{
    "name": "new_custom_function",
    "scm_id": 1,
    "description": "Example description. Can be any text.",
    "commit_message": "this custom function prints hello world",
    "python": "print(\"hello world\")"
}'

JSON response

{
    "warnings": [ ] ,
    "errors":  [ ] ,
    '"id":  2,
    "success":  true,
    "commit_sha":  "1ded5f50ac2e2790b3e2869f6e1487ffc4236856"
}

The ID passed back in the response is the newly created custom function. commit_sha is the commit for the new files.

GET

View a list of custom functions.

<Returned values>

None.

Notable parameters

Field	Required	Type	Description
commit_sha	optional	string	The most recent GIT commit identifier for the custom function.
disabled	optional	Boolean	Describes whether the custom function is active or inactive.
draft_mode	optional	Boolean	If you set the draft_mode field to true, you can see your draft mode versions of custom functions. If you set the draft_mode field to false, you can see your non-draft mode custom functions.
latest_editor	optional	integer	A foreign key to a PhUser model. This field reflects the last user that edited the custom function.
name	optional	string	The name of the custom function. This name is the same as the name on the custom function listing page.
scm	optional	integer	A foreign key to the SCM model. This field is the current repository where the custom function is saved.

Example request and response
Request to view the list of custom functions.

curl -k -u username:password  https://localhost/rest/custom_function/<id> -G -X GET

JSON response

{
    "count": 1,
    "data": [
        {
            "scm": 1,
            "platform_version": "4.8",
            "description": "This is a description",
            "latest_editor": 1,
            "json_blob_sha": "c7299d2825c823d24d2570bed7f2321bee7113ef",
            "draft_mode": false,
            "forked_from": null,
            "commit_sha": "7e08d23bd11bc3043e0872a58e8ead0722edc3b3",
            "python_blob_sha": "37422d6dc6e7fee1b05b2a9fc58edceb0a0d069f",
            "scm_user_name": "",
            "last_updated_time": "2020-01-01T01:00:00Z",
            "version": 1,
            "passed_validation": true,
            "date_created": "2020-01-01T01:00:00Z",
            "disabled": false,
            "id": 1,
            "custom_function_id": "930b704e669274d0fb9293d1db5bdc5f0c457304",
            "name": "example_custom_function"
        }
    ],
    "num_pages": 1
}

/rest/custom_function/<id>

https://<username>:<password>@<host>/rest/custom_function/<id>

Update a custom function, or view a list of all custom functions.

POST

Update a custom function.

You can't update the name or scm_id fields of an existing custom function. Because you can't update the fields, when you make a POST request, make sure to either match the name and scm_id fields in the request body, or don't include the name and scm_id fields in the request body in order for it to pass. If you want to change the name and scm_id fields of the custom function, you need to create a copy.

<Returned values>

None.

Fields for both creating and updating a custom function

Field	Required	Type	Default	Description
draft_mode	optional	Boolean	true	A flag to mark a custom function as a draft version. This flag allows you to save invalid Python code while draft_mode is set to true.
python	optional	string	true	Python code that runs for the custom function when it is included in a playbook.
description	optional	string	true	Descriptive text for the custom function. This field is shown when selecting custom functions inside the playbook editor.
commit_message	Dependency of a Python field	string	true	This field is required if the Python field is passed. This message is used for the commit of the changed Python and metadata files to the connected repository.
inputs	optional	JSON object	{}	Inputs are used for configuring the custom function in the playbook editor. Example value: [ { "description: "fgh", "contains_type" : ["ip"] , "name": "fgh" } ]
outputs	optional	JSON object	{}	Outputs are used for configuring downstream blocks from the custom function in the playbook editor. Example value: [ { "data_path": "ip", "description": "This is an ip", "contains_type" : ["ip"], } ]

Example request and response
This example JSON request shows creating the draft version of a non-draft custom function, and giving that draft version a different description. This request doesn't disable the current custom function, so it doesn't affect any playbooks using this custom function.

JSON request

curl -k -u username:password https://localhost/rest/custom_function/1 \
-d '{
    "description": "Example description. Can be any text.",
    "draft_mode": true
}'

JSON response

{
    "warnings": [ ] ,
    "errors":  [ ] ,
    '"id":  2,
    "success":  true,
    "commit_sha":  "1ded5f50ac2e2790b3e2869f6e1487ffc4236856"
}

The ID passed back in the response is the newly created custom function. commit_sha is the commit for the new files.

GET

View a single custom function or a list of custom functions.

<Returned values>

None.

Notable parameters

Field	Required	Type	Description
commit_sha	optional	string	The most recent GIT commit identifier for the custom function.
disabled	optional	Boolean	Describes whether the custom function is active or inactive.
draft_mode	optional	Boolean	If you set the draft_mode field to true, you can see your draft mode versions of custom functions. If you set the draft_mode field to false, you can see your non-draft mode custom functions.
latest_editor	optional	integer	A foreign key to a PhUser model. This foreign key reflects the last user that edited the custom function.
name	optional	string	The name of the custom function. This name is the same as the name in the custom function listing page.
scm	optional	integer	A foreign key to the SCM model. This foreign key is the current repository where the custom function is saved.

Example request and response

JSON request

curl -k -u username:password https://localhost/rest/custom_function/<id> -G -X GET

Request to view a single custom function.

JSON response

{
    "playbooks": [
        {
            "active": true,
            "draft_mode": false,
            "name": "toggle_playbook_active",
            "id": 1
        }
    ],
    "disabled": false,
    "scm_user_name": "",
    "create_time": "2020-01-01T01:00:00Z",
    "id": 1,
    "scm_id": 1,
    "latest_editor": 1,
    "warnings": [],
    "commit_sha": "7e08d23bd11bc3043e0872a58e8ead0722edc3b3",
    "platform_version": "4.8",
    "version": 10,
    "passed_validation": true,
    "inputs": [
        {
            "custom_function": 10,
            "description": "",
            "contains_type": [
                "*"
            ],
            "id": 10,
            "name": "input_1"
        }
    ],
    "description": "This is a description",
    "draft_mode": false,
    "python": "def example_custom_function(input_1=None, **kwargs): return {} ",
    "outputs": [],
    "errors": [],
    "custom_function_id": "930b704e669274d0fb9293d1db5bdc5f0c457304",
    "name": "example_custom_function",
    "json_blob_sha": "c7299d2825c823d24d2570bed7f2321bee7113ef",
    "forked_from": null,
    "python_blob_sha": "37422d6dc6e7fee1b05b2a9fc58edceb0a0d069f",
    "date_created": "2020-01-01T01:00:00Z"
}

/rest/import_custom_function

POST

Imports a custom function.

Request parameters

Field	Required	Type	Description
custom_function	Required	String	The base64-encoded, gzipped custom function TAR file that you want to import.
scm/scm_id	Required	Name or ID of the repository	The repository where the custom function is saved.
force	Optional	boolean	Set to true to override an existing custom function in the same repository with the same name.

Example request
Imports a custom function.

curl -k -u username:password https://localhost/rest/import_custom_function \
-d '{
  "custom_function": "H4sIAAILU2UC/+2X3U/bMBDA+8xfcSovwEZwnKYhlZCmMWnTNG3TxrSHaarc5EINSRzFDqVD/O87Jyl0TLCXwTTw76FO7Dvfhz9y9fa8vRcfxfkbFCnWg3uBddzWMhaMrp9tv8+4zwdwPngAGm1ETeYHTxO+D4WRBR744ziMQh7FzItC5u9HfGPgePSUSlVetbxXG/ZQj0ftGfdpb623Fp9H/o3zzwMWDIA95Pmv5qI0qrhV7k/j/ykpZmD3wNbOzulC1Md6e7IBxHA4bNtXiobNXJbHIMoUajRNXa66PPiiEehRg8xgqRpYUJLAKEgVaFVgpyhLEJBQolUBWVMmRqoSNM1U0W/3pmrIUZwhCVa5SHCucvocwSxXyWmnT93LmVKnHhxZe6lCbd0AnSNWVn8hpGl9XMg8XzkqNPmh2rZSWstZjl4bV/vzqRXSNPvbzx/e72qspcjlD0FSoGYn5BsFJwzIosqxwNJoekdIVJnJ46bGFFJhyDVh5rpL29XUq/xt3gEcdjk5VCnCaxvQS8zVogvwnSzxTu2W1ga5p2oDJ1qV6+/9jvXqJqepbQa6juv4VWOqhoI6gIvLX93f7HNzR2paOaFppDPtpU1R6a1+zm07x9d2JYSkTSJKwPMEq3a1abPYPE562ckq2bJb0t8stqb6Fe113Mfp7+C5+s/Vf67+e9r1n72+/139x2jb3az/xjxy9d9DcNFVK0mNwuDU3gTDCQw5XcC7bLTL94/8eBIGE+57fhhHbPSMsQljw+e9WlvATFdF3VSmVjsc+wl9TTLOuYg5m81iP+HBOBljjLNozEZZGETBOF7NkqJOatmWBlb9EZacV5HWIjPTguo9CjQTucZ+QJa2qKHOb9/7nr7OWe8if0ym6mJ6hrXukzXyfOYFXkh/maKVlWpp5rQYa1LBcOPS3XUOh8PhcDgcDofD4XA4HA6Hw/GU+AlQtUisACgAAA==",
	"scm": "local",
	"force": true
}'

Example response
A successful POST returns a success indicator and an import message.

{
    "success": true,
    "message": [
        true,
        "Custom function \"custom_function\" imported"
    ]
}

/rest/custom_function/<id>/export

GET

Exports a custom function.

Example request
Export a custom function.

curl -k -u username:password --output <FILE> https://localhost/rest/custom_function/1/export 

Example response
A successful GET returns an x-gzip file to the location set in the --output flag.